home *** CD-ROM | disk | FTP | other *** search
/ Network PC / Network PC.iso / amiga utilities / communication / internet / amitcp3.0b / src.lha / src / amitcp / api / auto_extras.c < prev    next >
Encoding:
C/C++ Source or Header  |  1996-09-08  |  8.7 KB  |  269 lines
  1. /****** bsdsocket.library/Errno *********************************************
  2. *
  3. *   NAME
  4. *        Errno - get error value after unsuccessful function call
  5. *
  6. *   SYNOPSIS
  7. *        errno = Errno()
  8. *        D0
  9. *
  10. *        LONG Errno(VOID);
  11. *
  12. *   FUNCTION
  13. *        When  some  function  in  socket  library  return  an  error
  14. *        condition value, they also set a specific error value.  This
  15. *        error value can be extracted by this function.
  16. *
  17. *   RESULT
  18. *        Error value  indicating  the error on  last failure  of some
  19. *        socket function call.
  20. *
  21. *   NOTES
  22. *        Return  value  of  Errno()  is not changed  after successful
  23. *        function so so it cannot be used to determine success of any
  24. *        function call  of this library.  Also, another function call
  25. *        to this  library may change  the return value of  Errno() so
  26. *        use it right after error occurred.
  27. *
  28. *   SEE ALSO
  29. *        SetErrnoPtr()
  30. *
  31. *****************************************************************************
  32. *
  33. */
  34.  
  35.  
  36. /****** bsdsocket.library/ObtainSocket **************************************
  37. *
  38. *   NAME
  39. *        ObtainSocket - get a socket from AmiTCP/IP socket list
  40. *
  41. *   SYNOPSIS
  42. *        s = ObtainSocket(id, domain, type, protocol)
  43. *        D0               D0  D1      D2    D3
  44. *
  45. *        LONG ObtainSocket(LONG, LONG, LONG, LONG);
  46. *
  47. *   FUNCTION 
  48. *        When one task wants to give  a socket to  an another one, it
  49. *        releases it (with a key value) to a special socket list held
  50. *        by  AmiTCP/IP.   This  function  requests  that  socket  and
  51. *        receives it if id and other parameters match.
  52. *
  53. *   INPUTS
  54. *        id       - a key value given by the socket donator.
  55. *        domain   - see documentation of socket().
  56. *        type     - see documentation of socket().
  57. *        protocol - see documentation of socket().
  58. *
  59. *   RESULT
  60. *        Non negative socket descriptor on success. On failure, -1 is
  61. *        returned and the errno is set to indicate the error.
  62. *
  63. *   ERRORS
  64. *        EMFILE          - The per-process descriptor table is
  65. *                          full.
  66. *
  67. *        EPROTONOSUPPORT - The protocol type or the specified  pro-
  68. *                          tocol is not supported within this
  69. *                          domain.
  70. *
  71. *        EPROTOTYPE      - The protocol is the wrong type for the
  72. *                          socket.
  73. *
  74. *        EWOULDBLOCK     - Matching socket is not found.
  75. *         
  76. *   SEE ALSO
  77. *        ReleaseCopyOfSocket(), ReleaseSocket(), socket()
  78. *
  79. *****************************************************************************
  80. *
  81. */
  82.  
  83. /****** bsdsocket.library/ReleaseCopyOfSocket *******************************
  84. *
  85. *   NAME
  86. *        ReleaseCopyOfSocket - copy given socket to AmiTCP/IP socket list.
  87. *
  88. *   SYNOPSIS
  89. *        id = ReleaseCopyOfSocket(fd, id)
  90. *        D0                       D0  D1
  91. *
  92. *        LONG ReleaseCopyOfSocket(LONG, LONG);
  93. *
  94. *   FUNCTION
  95. *        Make a new reference to a given socket (pointed by its descriptor)
  96. *        and release it to the socket list held by AmiTCP/IP.
  97. *
  98. *   INPUTS
  99. *        fd - descriptor of the socket to release.
  100. *
  101. *        id - the key value to identify use of this socket. It can be
  102. *             unique or not, depending on its  value.  If id value is
  103. *             between 0  and  65535,  inclusively,  it is  considered
  104. *             nonunique  and it can  be  used as a port  number,  for
  105. *             example.   If  id is greater  than  65535 and less than
  106. *             2^31) it  must be unique in currently  held sockets  in
  107. *             AmiTCP/IP socket  list,  Otherwise  an  error  will  be
  108. *             returned  and  socket  is  not  released.    If  id  ==
  109. *             UNIQUE_ID (defined in <sys/socket.h>) an unique id will
  110. *             be generated.
  111. *
  112. *   RESULT
  113. *        id - -1 in case of error and the key value of the socket put
  114. *             in the list. Most useful when an unique id is generated
  115. *             by this routine. 
  116. *
  117. *   ERRORS
  118. *        EINVAL - Requested unique id is already used.
  119. *
  120. *        ENOMEM - Needed memory couldn't be allocated.
  121. *
  122. *   NOTE
  123. *        The socket descriptor is not deallocated.
  124. *
  125. *   SEE ALSO
  126. *        ObtainSocket(), ReleaseSocket()
  127. *
  128. *
  129. *****************************************************************************
  130. *
  131. */
  132.  
  133. /****** bsdsocket.library/ReleaseSocket *************************************
  134. *
  135. *   NAME
  136. *        ReleaseSocket - release given socket to AmiTCP/IP socket list.
  137. *
  138. *   SYNOPSIS
  139. *        id = ReleaseSocket(fd, id)
  140. *        D0                 D0  D1
  141. *
  142. *        LONG ReleaseSocket(LONG, LONG);
  143. *
  144. *   FUNCTION
  145. *        Release the reference of given socket (via  its  descriptor)
  146. *        and move the socket to the  socket  list held by  AmiTCP/IP.
  147. *        The socket descriptor is deallocated in this procedure.
  148. *
  149. *   INPUTS
  150. *        fd - descriptor of the socket to release.
  151. *
  152. *        id - the key value to identify use of this socket. It can be
  153. *             unique or not, depending on its  value.  If id value is
  154. *             between 0  and  65535,  inclusively,  it is  considered
  155. *             nonunique  and it can  be  used as a port  number,  for
  156. *             example.   If  id is greater  than  65535 and less than
  157. *             2^31) it  must be unique in currently  held sockets  in
  158. *             AmiTCP/IP socket  list,  Otherwise  an  error  will  be
  159. *             returned  and  socket  is  not  released.    If  id  ==
  160. *             UNIQUE_ID (defined in <sys/socket.h>) an unique id will
  161. *             be generated.
  162. *
  163. *   RESULT
  164. *        id - -1 in case of error and the key value of the socket put
  165. *             in the list. Most useful when an unique id is generated
  166. *             by this routine. 
  167. *
  168. *   ERRORS
  169. *        EINVAL - Requested unique id is already used.
  170. *
  171. *        ENOMEM - Needed memory couldn't be allocated.
  172. *
  173. *   SEE ALSO
  174. *        ObtainSocket(), ReleaseCopyOfSocket()
  175. *
  176. *****************************************************************************
  177. *
  178. */
  179.  
  180. /****** bsdsocket.library/SetErrnoPtr ***************************************
  181. *
  182. *   NAME
  183. *        SetErrnoPtr - set new place where the error value will be written
  184. *
  185. *   SYNOPSIS
  186. *        SetErrnoPtr(ptr, size)
  187. *                    A0   D0
  188. *
  189. *        VOID SetErrnoPtr(VOID *, UBYTE);
  190. *
  191. *   FUNCTION
  192. *        This functions allows caller to redirect error variable inside
  193. *        scope of  caller task.   Usually this is  used to make  task's
  194. *        global variable errno as error variable.
  195. *
  196. *   INPUTS
  197. *        ptr     - pointer to error variable that is to be modified on
  198. *                  every error condition on this library function.
  199. *        size    - size of the error variable.
  200. * 
  201. *   EXAMPLE
  202. *        #include <errno.h>
  203. *
  204. *        struct Library;
  205. *        struct Library * SocketBase = NULL;
  206. *
  207. *        int main(void)
  208. *        {
  209. *           ...
  210. *          if ((SocketBase = OpenLibrary("bsdsocket.library", 2))
  211. *              != NULL) {
  212. *            SetErrnoPtr(&errno, sizeof(errno));
  213. *           ...
  214. *          }
  215. *        }
  216. *
  217. *   NOTES
  218. *        Be sure that this new error variable exists until library base
  219. *        is finally closed or SetErrnoPtr() is called again for another
  220. *        variable.
  221. *
  222. *   SEE ALSO
  223. *        Errno()
  224. *
  225. *****************************************************************************
  226. *
  227. */
  228.  
  229. /****** bsdsocket.library/SetSocketSignals **********************************
  230. *
  231. *   NAME
  232. *        SetSocketSignals - inform AmiTCP/IP of INTR, IO and URG signals
  233. *
  234. *   SYNOPSIS
  235. *        SetSocketSignals(sigintrmask, sigiomask, sigurgmask)
  236. *                         D0           D1         D2
  237. *
  238. *        VOID SetSocketSignals(ULONG, ULONG, ULONG);
  239. *
  240. *   FUNCTION
  241. *        SetSocketSignals() tells  the  AmiTCP/IP which signal  masks
  242. *        corresponds UNIX SIGINT, SIGIO and SIGURG signals to be used
  243. *        in   this implementation.  The  sigintrmask  mask is used to
  244. *        determine which  Amiga  signals interrupt  blocking  library
  245. *        calls.
  246. *
  247. *        The sigiomask  is sent  when  asynchronous  notification  of
  248. *        socket   events   is  done,  the sigurgmask    is  sent when
  249. *        out-of-band   data  arrives, respectively.   The signals are
  250. *        sent only  to  the owning task  of   particular socket.  The
  251. *        socket  has got no owner   by default; the  owner  is set by
  252. *        FIOSETOWN (SIOCSPGRP) ioctl call.
  253. *
  254. *        Note that the supplied  values write over  old ones. If this
  255. *        function is used and CTRL-C is still wanted to interrupt the
  256. *        calls (the default behaviour),  the value BREAKF_CTRL_C must
  257. *        be explicitly given.
  258. *
  259. *   NOTES
  260. *        The function SetSocketSignals() is obsoleted by the function
  261. *        SocketBaseTags().
  262. *
  263. *   SEE ALSO
  264. *        IoctlSocket(), recv(), send(), select(), WaitSelect()
  265. *
  266. *****************************************************************************
  267. * 
  268. */
  269.